fix docs+examples, work without reset, fixes #365

burrbull · 2019-08-04T06:07:28Z

Add more docs as @Disasm proposed.

Restore unsafe on W::bits() I somewhere lost.

Don't generate write if reset_value is not present. #258

therealprof · 2019-08-04T09:47:28Z

src/lib.rs

+//!
+//! `ResetValue` trait provides `reset_value` which returns the value of the `CR2`
+//! register after a reset. This value can be used to modify the
+//! writable bitfields of the `CR2` register or reset it in initial state.


Suggested change

//! writable bitfields of the `CR2` register or reset it in initial state.

//! writable bitfields of the `CR2` register or reset it to its initial state.

therealprof · 2019-08-04T09:48:04Z

src/lib.rs

@@ -256,26 +262,30 @@
 //! }
 //! ```
 //!
+//! ## `reset`
+//!
+//! `ResetValue` trait provides `reset_value` which returns the value of the `CR2`


Suggested change

//! `ResetValue` trait provides `reset_value` which returns the value of the `CR2`

//! The `ResetValue` trait provides `reset_value` which returns the value of the `CR2`

therealprof · 2019-08-04T09:50:30Z

src/generate/generic.rs

@@ -165,16 +208,18 @@ impl<FI> R<bool, FI> {
 }

 ///Register writer
+///
+///It is used as argument of closures in [`write`](Reg::write) and [`modify`](Reg::modify) methods of register


Suggested change

///It is used as argument of closures in [`write`](Reg::write) and [`modify`](Reg::modify) methods of register

///Used as an argument to the closures in the [`write`](Reg::write) and [`modify`](Reg::modify) methods of the register

therealprof · 2019-08-04T09:51:16Z

src/generate/generic.rs

@@ -112,6 +151,9 @@ where
 }

 ///Register/field reader
+///
+///Result of call [`read`](Reg::read) method of register.


Suggested change

///Result of call [`read`](Reg::read) method of register.

///Result of the [`read`](Reg::read) method of a register.

therealprof · 2019-08-04T09:51:57Z

src/generate/generic.rs

@@ -112,6 +151,9 @@ where
 }

 ///Register/field reader
+///
+///Result of call [`read`](Reg::read) method of register.
+///Also it can be used in [`modify`](Reg::read) method


Suggested change

///Also it can be used in [`modify`](Reg::read) method

///Also it can be used in the [`modify`](Reg::read) method

therealprof · 2019-08-04T09:53:51Z

src/generate/generic.rs

@@ -100,7 +125,21 @@ where
 {
    ///Modifies the contents of the register
    ///
-    ///See [modifying](https://rust-embedded.github.io/book/start/registers.html#modifying) in book.
+    ///Change only part of register:


Suggested change

///Change only part of register:

///E.g. to do a read-modify-write sequence to change parts of a register:

therealprof · 2019-08-04T09:54:10Z

src/generate/generic.rs

+    ///or
+    ///```ignore
+    ///periph.reg.modify(|_, w| w
+    ///    .field1() .bits(newfield1bits)


Suggested change

/// .field1() .bits(newfield1bits)

/// .field1().bits(newfield1bits)

therealprof · 2019-08-04T09:54:22Z

src/generate/generic.rs

+    ///```ignore
+    ///periph.reg.modify(|_, w| w
+    ///    .field1() .bits(newfield1bits)
+    ///    .field2() .set_bit()


Suggested change

/// .field2() .set_bit()

/// .field2().set_bit()

therealprof · 2019-08-04T09:54:41Z

src/generate/generic.rs

+    ///periph.reg.modify(|_, w| w
+    ///    .field1() .bits(newfield1bits)
+    ///    .field2() .set_bit()
+    ///    .field3() .variant(VARIANT)


Suggested change

/// .field3() .variant(VARIANT)

/// .field3().variant(VARIANT)

therealprof · 2019-08-04T09:55:22Z

src/generate/generic.rs

+    ///or write only fields you need:
+    ///```ignore
+    ///periph.reg.write(|w| w
+    ///    .field1() .bits(newfield1bits)


Suggested change

/// .field1() .bits(newfield1bits)

/// .field1().bits(newfield1bits)

therealprof · 2019-08-04T09:55:33Z

src/generate/generic.rs

+    ///```ignore
+    ///periph.reg.write(|w| w
+    ///    .field1() .bits(newfield1bits)
+    ///    .field2() .set_bit()


Suggested change

/// .field2() .set_bit()

/// .field2().set_bit()

therealprof · 2019-08-04T09:55:50Z

src/generate/generic.rs

+    ///periph.reg.write(|w| w
+    ///    .field1() .bits(newfield1bits)
+    ///    .field2() .set_bit()
+    ///    .field3() .variant(VARIANT)


Suggested change

/// .field3() .variant(VARIANT)

/// .field3().variant(VARIANT)

therealprof · 2019-08-04T09:56:31Z

src/generate/generic.rs

@@ -68,7 +79,19 @@ where
 {
    ///Writes bits to `Writable` register
    ///
-    ///See [writing](https://rust-embedded.github.io/book/start/registers.html#writing) in book.
+    ///You can write raw bits into register:


Suggested change

///You can write raw bits into register:

///You can write raw bits into a register:

therealprof · 2019-08-04T09:57:19Z

src/generate/generic.rs

+    ///```ignore
+    ///periph.reg.write(|w| unsafe { w.bits(rawbits) });
+    ///```
+    ///or write only fields you need:


Suggested change

///or write only fields you need:

///or write only the fields you need:

therealprof · 2019-08-04T09:57:34Z

src/generate/generic.rs

@@ -42,7 +42,16 @@ where
 {
    ///Reads the contents of `Readable` register
    ///
-    ///See [reading](https://rust-embedded.github.io/book/start/registers.html#reading) in book.
+    ///You can read contents of register in such way:


Suggested change

///You can read contents of register in such way:

///You can read the contents of a register in such way:

therealprof · 2019-08-04T09:58:00Z

src/generate/generic.rs

+    ///```ignore
+    ///let bits = periph.reg.read().bits();
+    ///```
+    ///or get contents of particular field of register.


Suggested change

///or get contents of particular field of register.

///or get the content of a particular field of a register.

therealprof · 2019-08-04T09:59:00Z

src/generate/generic.rs

@@ -55,6 +64,8 @@ where
    U: Copy,
 {
    ///Writes the reset value to `Writable` register
+    ///
+    ///After call this method register takes the initial state


Suggested change

///After call this method register takes the initial state

///Resets the register to its initial state

therealprof

Also should have a CHANGELOG entry mentioning the do improvements and examples. And I think the unsafe problem has snuck in in V0.15.0 because I was looking at weird "don't need unsafe here" and after removal "you do need unsafe here" warning/errors just yesterday; in that case we also need a CHANGELOG entry for this.

burrbull · 2019-08-04T11:19:27Z

Done. Rebased.

therealprof

LGTM, thanks!

therealprof · 2019-08-04T11:22:55Z

bors r+

@therealprof

365: fix docs+examples, work without reset, fixes r=therealprof a=burrbull r? @therealprof Add more docs as @Disasm proposed. Restore `unsafe` on `W::bits()` I somewhere lost. Don't generate `write` if `reset_value` is not present. #258 Co-authored-by: Andrey Zgarbul <[email protected]>

bors · 2019-08-04T12:10:36Z

Build succeeded

continuous-integration/travis-ci/push

burrbull requested a review from a team as a code owner August 4, 2019 06:07

rust-highfive assigned therealprof Aug 4, 2019

rust-highfive added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-tools labels Aug 4, 2019

therealprof reviewed Aug 4, 2019

View reviewed changes

therealprof requested changes Aug 4, 2019

View reviewed changes

fix docs+examples, work without reset

fe27531

burrbull force-pushed the docs branch from 938a31d to fe27531 Compare August 4, 2019 11:19

therealprof approved these changes Aug 4, 2019

View reviewed changes

bors bot merged commit fe27531 into rust-embedded:master Aug 4, 2019

burrbull deleted the docs branch August 4, 2019 14:17

	//! writable bitfields of the `CR2` register or reset it in initial state.
	//! writable bitfields of the `CR2` register or reset it to its initial state.

	//! `ResetValue` trait provides `reset_value` which returns the value of the `CR2`
	//! The `ResetValue` trait provides `reset_value` which returns the value of the `CR2`

	///It is used as argument of closures in [`write`](Reg::write) and [`modify`](Reg::modify) methods of register
	///Used as an argument to the closures in the [`write`](Reg::write) and [`modify`](Reg::modify) methods of the register

	///Result of call [`read`](Reg::read) method of register.
	///Result of the [`read`](Reg::read) method of a register.

	///Also it can be used in [`modify`](Reg::read) method
	///Also it can be used in the [`modify`](Reg::read) method

	///Change only part of register:
	///E.g. to do a read-modify-write sequence to change parts of a register:

	/// .field1() .bits(newfield1bits)
	/// .field1().bits(newfield1bits)

	/// .field3() .variant(VARIANT)
	/// .field3().variant(VARIANT)

	///You can write raw bits into register:
	///You can write raw bits into a register:

	///or write only fields you need:
	///or write only the fields you need:

	///You can read contents of register in such way:
	///You can read the contents of a register in such way:

	///or get contents of particular field of register.
	///or get the content of a particular field of a register.

	///After call this method register takes the initial state
	///Resets the register to its initial state

fix docs+examples, work without reset, fixes #365

fix docs+examples, work without reset, fixes #365

Uh oh!

Conversation

burrbull commented Aug 4, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

therealprof left a comment

Choose a reason for hiding this comment

Uh oh!

burrbull commented Aug 4, 2019

Uh oh!

therealprof left a comment

Choose a reason for hiding this comment

Uh oh!

therealprof commented Aug 4, 2019

Uh oh!

bors bot commented Aug 4, 2019

Build succeeded

Uh oh!

Uh oh!